<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="os-file-dir.html" />
<link rel="prev" href="os-newstreams.html" />
<link rel="parent" href="module-os.html" />
<link rel="next" href="os-file-dir.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>14.1.3 File Descriptor Operations </title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="14.1.2 file Object Creation"
  href="os-newstreams.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="14.1 os  "
  href="module-os.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="14.1.4 files and Directories"
  href="os-file-dir.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="os-newstreams.html">14.1.2 File Object Creation</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-os.html">14.1 os  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="os-file-dir.html">14.1.4 Files and Directories</a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h2><a name="SECTION0016130000000000000000"></a><a name="os-fd-ops"></a>
<br>
14.1.3 File Descriptor Operations 
</h2>

<p>
These functions operate on I/O streams referenced using file
descriptors.  

<p>
File descriptors are small integers corresponding to a file that has
been opened by the current process.  For example, standard input is
usually file descriptor 0, standard output is 1, and standard error is
2.  Further files opened by a process will then be assigned 3, 4, 5,
and so forth.  The name ``file descriptor'' is slightly deceptive; on
<span class="Unix">Unix</span> platforms, sockets and pipes are also referenced by file descriptors.

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2631' xml:id='l2h-2631' class="function">close</tt></b>(</nobr></td>
  <td><var>fd</var>)</td></tr></table></dt>
<dd>
Close file descriptor <var>fd</var>.
Availability: Macintosh, <span class="Unix">Unix</span>, Windows.

<p>
<div class="note"><b class="label">Note:</b>
This function is intended for low-level I/O and must be applied
to a file descriptor as returned by <tt class="function">open()</tt> or
<tt class="function">pipe()</tt>.  To close a ``file object'' returned by the
built-in function <tt class="function">open()</tt> or by <tt class="function">popen()</tt> or
<tt class="function">fdopen()</tt>, use its <tt class="method">close()</tt> method.
</div>
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2632' xml:id='l2h-2632' class="function">dup</tt></b>(</nobr></td>
  <td><var>fd</var>)</td></tr></table></dt>
<dd>
Return a duplicate of file descriptor <var>fd</var>.
Availability: Macintosh, <span class="Unix">Unix</span>, Windows.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2633' xml:id='l2h-2633' class="function">dup2</tt></b>(</nobr></td>
  <td><var>fd, fd2</var>)</td></tr></table></dt>
<dd>
Duplicate file descriptor <var>fd</var> to <var>fd2</var>, closing the latter
first if necessary.
Availability: Macintosh, <span class="Unix">Unix</span>, Windows.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2634' xml:id='l2h-2634' class="function">fdatasync</tt></b>(</nobr></td>
  <td><var>fd</var>)</td></tr></table></dt>
<dd>
Force write of file with filedescriptor <var>fd</var> to disk.
Does not force update of metadata.
Availability: <span class="Unix">Unix</span>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2635' xml:id='l2h-2635' class="function">fpathconf</tt></b>(</nobr></td>
  <td><var>fd, name</var>)</td></tr></table></dt>
<dd>
Return system configuration information relevant to an open file.
<var>name</var> specifies the configuration value to retrieve; it may be a
string which is the name of a defined system value; these names are
specified in a number of standards (POSIX.1, <span class="Unix">Unix</span> 95, <span class="Unix">Unix</span> 98, and
others).  Some platforms define additional names as well.  The names
known to the host operating system are given in the
<code>pathconf_names</code> dictionary.  For configuration variables not
included in that mapping, passing an integer for <var>name</var> is also
accepted.
Availability: Macintosh, <span class="Unix">Unix</span>.

<p>
If <var>name</var> is a string and is not known, <tt class="exception">ValueError</tt> is
raised.  If a specific value for <var>name</var> is not supported by the
host system, even if it is included in <code>pathconf_names</code>, an
<tt class="exception">OSError</tt> is raised with <tt class="constant">errno.EINVAL</tt> for the
error number.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2636' xml:id='l2h-2636' class="function">fstat</tt></b>(</nobr></td>
  <td><var>fd</var>)</td></tr></table></dt>
<dd>
Return status for file descriptor <var>fd</var>, like <tt class="function">stat()</tt>.
Availability: Macintosh, <span class="Unix">Unix</span>, Windows.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2637' xml:id='l2h-2637' class="function">fstatvfs</tt></b>(</nobr></td>
  <td><var>fd</var>)</td></tr></table></dt>
<dd>
Return information about the filesystem containing the file associated
with file descriptor <var>fd</var>, like <tt class="function">statvfs()</tt>.
Availability: <span class="Unix">Unix</span>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2638' xml:id='l2h-2638' class="function">fsync</tt></b>(</nobr></td>
  <td><var>fd</var>)</td></tr></table></dt>
<dd>
Force write of file with filedescriptor <var>fd</var> to disk.  On <span class="Unix">Unix</span>,
this calls the native <tt class="cfunction">fsync()</tt> function; on Windows, the
MS <tt class="cfunction">_commit()</tt> function.

<p>
If you're starting with a Python file object <var>f</var>, first do
<code><var>f</var>.flush()</code>, and then do <code>os.fsync(<var>f</var>.fileno())</code>,
to ensure that all internal buffers associated with <var>f</var> are written
to disk.
Availability: Macintosh, <span class="Unix">Unix</span>, and Windows starting in 2.2.3.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2639' xml:id='l2h-2639' class="function">ftruncate</tt></b>(</nobr></td>
  <td><var>fd, length</var>)</td></tr></table></dt>
<dd>
Truncate the file corresponding to file descriptor <var>fd</var>,
so that it is at most <var>length</var> bytes in size.
Availability: Macintosh, <span class="Unix">Unix</span>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2640' xml:id='l2h-2640' class="function">isatty</tt></b>(</nobr></td>
  <td><var>fd</var>)</td></tr></table></dt>
<dd>
Return <code>True</code> if the file descriptor <var>fd</var> is open and
connected to a tty(-like) device, else <code>False</code>.
Availability: Macintosh, <span class="Unix">Unix</span>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2641' xml:id='l2h-2641' class="function">lseek</tt></b>(</nobr></td>
  <td><var>fd, pos, how</var>)</td></tr></table></dt>
<dd>
Set the current position of file descriptor <var>fd</var> to position
<var>pos</var>, modified by <var>how</var>: <code>0</code> to set the position
relative to the beginning of the file; <code>1</code> to set it relative to
the current position; <code>2</code> to set it relative to the end of the
file.
Availability: Macintosh, <span class="Unix">Unix</span>, Windows.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2642' xml:id='l2h-2642' class="function">open</tt></b>(</nobr></td>
  <td><var>file, flags</var><big>[</big><var>, mode</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Open the file <var>file</var> and set various flags according to
<var>flags</var> and possibly its mode according to <var>mode</var>.
The default <var>mode</var> is <code>0777</code> (octal), and the current umask
value is first masked out.  Return the file descriptor for the newly
opened file.
Availability: Macintosh, <span class="Unix">Unix</span>, Windows.

<p>
For a description of the flag and mode values, see the C run-time
documentation; flag constants (like <tt class="constant">O_RDONLY</tt> and
<tt class="constant">O_WRONLY</tt>) are defined in this module too (see below).

<p>
<div class="note"><b class="label">Note:</b>
This function is intended for low-level I/O.  For normal usage,
use the built-in function <tt class="function">open()</tt>, which returns a ``file
object'' with <tt class="method">read()</tt> and <tt class="method">write()</tt> methods (and many
more).  To wrap a file descriptor in a ``file object'', use
<tt class="function">fdopen()</tt>.
</div>
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2643' xml:id='l2h-2643' class="function">openpty</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Open a new pseudo-terminal pair. Return a pair of file descriptors
<code>(<var>master</var>, <var>slave</var>)</code> for the pty and the tty,
respectively. For a (slightly) more portable approach, use the
<tt class="module"><a href="module-pty.html">pty</a></tt><a id='l2h-2655' xml:id='l2h-2655'></a> module.
Availability: Macintosh, Some flavors of <span class="Unix">Unix</span>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2644' xml:id='l2h-2644' class="function">pipe</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Create a pipe.  Return a pair of file descriptors <code>(<var>r</var>,
<var>w</var>)</code> usable for reading and writing, respectively.
Availability: Macintosh, <span class="Unix">Unix</span>, Windows.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2645' xml:id='l2h-2645' class="function">read</tt></b>(</nobr></td>
  <td><var>fd, n</var>)</td></tr></table></dt>
<dd>
Read at most <var>n</var> bytes from file descriptor <var>fd</var>.
Return a string containing the bytes read.  If the end of the file
referred to by <var>fd</var> has been reached, an empty string is
returned.
Availability: Macintosh, <span class="Unix">Unix</span>, Windows.

<p>
<div class="note"><b class="label">Note:</b>
This function is intended for low-level I/O and must be applied
to a file descriptor as returned by <tt class="function">open()</tt> or
<tt class="function">pipe()</tt>.  To read a ``file object'' returned by the
built-in function <tt class="function">open()</tt> or by <tt class="function">popen()</tt> or
<tt class="function">fdopen()</tt>, or <code>sys.stdin</code>, use its
<tt class="method">read()</tt> or <tt class="method">readline()</tt> methods.
</div>
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2646' xml:id='l2h-2646' class="function">tcgetpgrp</tt></b>(</nobr></td>
  <td><var>fd</var>)</td></tr></table></dt>
<dd>
Return the process group associated with the terminal given by
<var>fd</var> (an open file descriptor as returned by <tt class="function">open()</tt>).
Availability: Macintosh, <span class="Unix">Unix</span>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2647' xml:id='l2h-2647' class="function">tcsetpgrp</tt></b>(</nobr></td>
  <td><var>fd, pg</var>)</td></tr></table></dt>
<dd>
Set the process group associated with the terminal given by
<var>fd</var> (an open file descriptor as returned by <tt class="function">open()</tt>)
to <var>pg</var>.
Availability: Macintosh, <span class="Unix">Unix</span>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2648' xml:id='l2h-2648' class="function">ttyname</tt></b>(</nobr></td>
  <td><var>fd</var>)</td></tr></table></dt>
<dd>
Return a string which specifies the terminal device associated with
file-descriptor <var>fd</var>.  If <var>fd</var> is not associated with a terminal
device, an exception is raised.
Availability:Macintosh,  <span class="Unix">Unix</span>.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-2649' xml:id='l2h-2649' class="function">write</tt></b>(</nobr></td>
  <td><var>fd, str</var>)</td></tr></table></dt>
<dd>
Write the string <var>str</var> to file descriptor <var>fd</var>.
Return the number of bytes actually written.
Availability: Macintosh, <span class="Unix">Unix</span>, Windows.

<p>
<div class="note"><b class="label">Note:</b>
This function is intended for low-level I/O and must be applied
to a file descriptor as returned by <tt class="function">open()</tt> or
<tt class="function">pipe()</tt>.  To write a ``file object'' returned by the
built-in function <tt class="function">open()</tt> or by <tt class="function">popen()</tt> or
<tt class="function">fdopen()</tt>, or <code>sys.stdout</code> or <code>sys.stderr</code>, use
its <tt class="method">write()</tt> method.
</div>
</dl>

<p>
The following data items are available for use in constructing the
<var>flags</var> parameter to the <tt class="function">open()</tt> function.  Some items will
not be available on all platforms.  For descriptions of their availability
and use, consult <span class="manpage"><i>open</i>(2)</span>.

<p>
<dl><dt><b><tt id='l2h-2650' xml:id='l2h-2650'>O_RDONLY</tt></b></dt>
<dd>
<dt><b><tt id='l2h-2656' xml:id='l2h-2656'>O_WRONLY</tt></b></dt><dd>
<dt><b><tt id='l2h-2657' xml:id='l2h-2657'>O_RDWR</tt></b></dt><dd>
<dt><b><tt id='l2h-2658' xml:id='l2h-2658'>O_APPEND</tt></b></dt><dd>
<dt><b><tt id='l2h-2659' xml:id='l2h-2659'>O_CREAT</tt></b></dt><dd>
<dt><b><tt id='l2h-2660' xml:id='l2h-2660'>O_EXCL</tt></b></dt><dd>
<dt><b><tt id='l2h-2661' xml:id='l2h-2661'>O_TRUNC</tt></b></dt><dd>
Options for the <var>flag</var> argument to the <tt class="function">open()</tt> function.
These can be bit-wise OR'd together.
Availability: Macintosh, <span class="Unix">Unix</span>, Windows.
</dd></dl>

<p>
<dl><dt><b><tt id='l2h-2651' xml:id='l2h-2651'>O_DSYNC</tt></b></dt>
<dd>
<dt><b><tt id='l2h-2662' xml:id='l2h-2662'>O_RSYNC</tt></b></dt><dd>
<dt><b><tt id='l2h-2663' xml:id='l2h-2663'>O_SYNC</tt></b></dt><dd>
<dt><b><tt id='l2h-2664' xml:id='l2h-2664'>O_NDELAY</tt></b></dt><dd>
<dt><b><tt id='l2h-2665' xml:id='l2h-2665'>O_NONBLOCK</tt></b></dt><dd>
<dt><b><tt id='l2h-2666' xml:id='l2h-2666'>O_NOCTTY</tt></b></dt><dd>
<dt><b><tt id='l2h-2667' xml:id='l2h-2667'>O_SHLOCK</tt></b></dt><dd>
<dt><b><tt id='l2h-2668' xml:id='l2h-2668'>O_EXLOCK</tt></b></dt><dd>
More options for the <var>flag</var> argument to the <tt class="function">open()</tt> function.
Availability: Macintosh, <span class="Unix">Unix</span>.
</dd></dl>

<p>
<dl><dt><b><tt id='l2h-2652' xml:id='l2h-2652'>O_BINARY</tt></b></dt>
<dd>
Option for the <var>flag</var> argument to the <tt class="function">open()</tt> function.
This can be bit-wise OR'd together with those listed above.
Availability: Windows.
</dd></dl>

<p>
<dl><dt><b><tt id='l2h-2653' xml:id='l2h-2653'>O_NOINHERIT</tt></b></dt>
<dd>
<dt><b><tt id='l2h-2669' xml:id='l2h-2669'>O_SHORT_LIVED</tt></b></dt><dd>
<dt><b><tt id='l2h-2670' xml:id='l2h-2670'>O_TEMPORARY</tt></b></dt><dd>
<dt><b><tt id='l2h-2671' xml:id='l2h-2671'>O_RANDOM</tt></b></dt><dd>
<dt><b><tt id='l2h-2672' xml:id='l2h-2672'>O_SEQUENTIAL</tt></b></dt><dd>
<dt><b><tt id='l2h-2673' xml:id='l2h-2673'>O_TEXT</tt></b></dt><dd>
Options for the <var>flag</var> argument to the <tt class="function">open()</tt> function.
These can be bit-wise OR'd together.
Availability: Windows.
</dd></dl>

<p>
<dl><dt><b><tt id='l2h-2654' xml:id='l2h-2654'>SEEK_SET</tt></b></dt>
<dd>
<dt><b><tt id='l2h-2674' xml:id='l2h-2674'>SEEK_CUR</tt></b></dt><dd>
<dt><b><tt id='l2h-2675' xml:id='l2h-2675'>SEEK_END</tt></b></dt><dd>
Parameters to the <tt class="function">lseek()</tt> function.
Their values are 0, 1, and 2, respectively.
Availability: Windows, Macintosh, <span class="Unix">Unix</span>.

<span class="versionnote">New in version 2.5.</span>

</dd></dl>

<p>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="14.1.2 file Object Creation"
  href="os-newstreams.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="14.1 os  "
  href="module-os.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="14.1.4 files and Directories"
  href="os-file-dir.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="os-newstreams.html">14.1.2 File Object Creation</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-os.html">14.1 os  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="os-file-dir.html">14.1.4 Files and Directories</a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
